\name{ContrastT}
\alias{ContrastT}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Contrast t-test}
\description{Calculate a t-test based on specified contrasts.  Works with more than two groups.  This documentation is mostly a stub.}
\usage{
ContrastT(x = NA, lambda, m = NULL, s = NULL, n = NULL, raw = TRUE)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{x}{
    A list of the data (if raw data) to use.  Each element should represent one group.
}
  \item{lambda}{
\code{lambda} weights (contrasts) to apply to the \code{data}.
}
  \item{m}{
The group \code{m}eans if they were pre-calculated or already given (as in an article or homework).
}
  \item{s}{
The group \code{s}tandard deviations if they were pre-calculated or already given.
}
  \item{n}{
The group sample sizes if they were pre-calculated or already given.
}
  \item{raw}{
\code{raw} defaults to TRUE.  It is a logical flag whether raw data or pre-calculated values should be used
}
}
\details{In some ways, all t-tests are contrasts.  For one-sample t-tests, the usual contrast (lambda) weight is just +1.  For a two-sample (independent) t-test, the usual contrast weights are +1 and -1, testing the hypothesis that the difference between the two means is equal to 0.

The advantage of allowing the contrast weights to be directly specified is that more complex hypotheses are testable.  For example, one might be interested in testing whether the mean of one group (H) is twice as high as the mean of a second group (L).  In this case, H - 2 * L = 0, so the weights would be \code{c(1, -2)}.  One can also test more than two groups at once.  For instance, one might test whether the linear trend across four groups is equal to 0.  The weights would be \code{c(-3, -1, +1, +3)}.
}
\value{
  \item{t.contrast}{The t-value for the specified contrast.}
  \item{p.value}{The one-tailed p-value for the obtained t-value}
  \item{r.contrast}{The effect size associated with the contrast.  See the references for this formula.}
  \item{pooled.variance}{The pooled variance from all groups.}
  \item{df}{The overall degrees of freedom (one degree of freedom is lost for each group mean estimated so it is the overal number of observations minus the number of groups).}

}
\references{
  Robert Rosenthal & Ralph L. Rosnow. \emph{Essentials of Behavioral Research: Methods and Data Analysis} (3rd ed.). McGraw-Hill, New York, 2008. ISBN 978-0-07-353196-0.
}
\author{Joshua Wiley, \url{http://joshuawiley.com/}}
%% \note{}
\section{Warning}{I wrote this when I did not know very much about R, and have not had time/interest to update it.  Use with caution.}

\seealso{\code{\link{t.test}}}

\examples{
## Data
set.seed(10)
dat <- list(
  w = rnorm(15),
  x = x <- rnorm(15, mean = 3),
  y = 2 * x + rnorm(15, sd = .1),
  z = x^2 + rnorm(15, sd = .1))

## "One-sample" t-test using contrasts
Jmisc:::ContrastT(x = dat["w"], lambda = 1)
## Using regular t-test
t.test(dat[["w"]], alternative = "greater")

## "Two-sample" t-test using contrasts
Jmisc:::ContrastT(x = dat[c("x", "w")], lambda = c(1, -1))
## Should be identical to above
t.test(x = dat$x, y = dat$w, var.equal = TRUE, alternative = "greater")

## Contrast that groups 'y' and 'z' are equal and greater than 'x'
Jmisc:::ContrastT(x = dat[c("x", "y", "z")], lambda = c(-2, 1, 1))

## Contrast that 'y' is twice 'x', that is
## that (2 * x) - y = 0
Jmisc:::ContrastT(x = dat[c("x", "y")], lambda = c(2, -1))

## Contrast to test whether a linear trend from 'w' to 'z' is 0
Jmisc:::ContrastT(x = dat, lambda = c(-3, -1, 1, 3))

rm(dat, x)
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{univar}
